=================================================================
ISTRUZIONI e SPECIFICHE per il FRAMMENTO 2 del PROGETTO "lcschat"
=================================================================

Il progetto prevede la realizzazione di un sistema client server che
implementa un chat distribuita. Il secondo frammento utilizza i pthread per
realizzare il server della chat. L'eseguibile del client e le librerie di
comunicazione fra client e server sono fornite nel presente kit e
verranno implementate dagli studenti nel terzo frammento.

-------------------------------------------------------
Backup del frammento 1
------------------------------------------------------

Siccome il file lcschat_kit2.tar va s-tarato sulla propria directory
di lavoro e sovrascrivera' alcuni dei vecchi file 
e' necessario prima di tutto effettuare un backup dei file
contenuti in essa. Ad esempio: posizionarsi nella directory che
contiene la cartella di progetto "lcschat" 
Creare una directory di backup *fuori da lcschat/**, copiare in essa tutti i
file del frammento 1 e proteggerli in scrittura.
Ad esempio:

bash:~$ mkdir BACK1
bash:~$ cp -fr lcschat BACK1
bash:~$ chmod a-w BACK1/*

Questo vi permettera' di recuperare  i file in caso di perdite accidentali (ad
esempio, se tar xvf sovrascrive i file). 


-----------------------------------------
Estrarre il materiale da lcschat_kit2.tar
-----------------------------------------

1) Copiare lcschat_kit2.tar nella directory che contiene lcschat/
es

bash:~$ ls
lcschat_kit2.tar lcschat/
bash:~$

2) s-tarare il file lcschat_kit2.tar

bash:~$ tar xvf kit2.tar

questa operazione creera' alcuni nuovi file nella directory prorub e ne
sovrascrivera' altri (per chiedere conferma della sovrascrittura e'
possibile settare esplicitamente l'opzione -k nel tar es: tar xkvf
...), 
in particolare: verranno create le directory
lcschat/bin/
lcschat/lib/
lcschat/test2/

ed i file
lcschat/bin/client
lcschat/bin/server
lcschat/bin/testclient
lcschat/README-2
lcschat/lcscom.h 
lcschat/lib/libcom.a
lcschat/test-frag2
lcschat/checktestfrag2out
lcschat/test2/clientciccio.check
lcschat/test2/clientciccio.test
lcschat/test2/clientminnie.check
lcschat/test2/clientminnie.test
lcschat/test2/clientpluto.check
lcschat/test2/clientpluto.test
lcschat/test2/outtest.check

mentre verranno sovrascritti i file
lcschat/lcshash,h
lcschat/Makefile
lcschat/test-frag1.c


-----------------------------------------------
Descrizione dei file contenuti in lcschat_kit2:
-----------------------------------------------

README-2		: questo file
			  (NON MODIFICARE)

lcshash.h		: macro, strutture dati e prototipi delle
			  funzioni relative alla tabella
			  hash. Rispetto al primo frammento sono state
			  modificate le specifiche di getHash() e
			  putHash() per rendere possibile una
			  implementazione senza race conditions usando
			  i pthread_mutex()
			  (NON MODIFICARE)

test-frag1.c		: il programma di test del primo frammento,
			  modificato per tener conto delle modifiche
			  in putHash() e getHash().
                          (NON MODIFICARE)

Makefile		: makefile per il test finale del frammento
			  due e la consegna (studenti LCS)
			  (NON MODIFICARE se non nella prima sezione
			  per aggiungere target -- vedi dopo)

Makefile2		: makefile per il test finale del frammento
			  due e la consegna (studenti LPS LPC -- recuperi)
			  (NON MODIFICARE se non nella prima sezione
			  per aggiungere target -- vedi dopo)

lcschat/lcscom.h	 : include della libreria di comunicazione fra
                           client e server(NON MODIFICARE)
lcschat/lib/libcom.a     : archivio libreria di comunicazione (da
                           linkare con "-L./lib -lcom")

lcschat/bin/             : directory contenente gli eseguibili di prova
                           
lcschat/bin/client	 : eseguibile client (input ed output TTY)
lcschat/bin/server	 : eseguibile server 
lcschat/bin/testclient   : eseguibile client (input ed output STDIN STDOUT)

test2/		        : directory con script ed output per il testing
test2/clientciccio.test	: client di prova ciccio(NON MODIFICARE)
test2/clientciccio.check: output atteso ciccio(NON MODIFICARE)
test2/clientminnie.test	: client di prova minnie(NON MODIFICARE)
test2/clientminnie.check: output atteso minnie(NON MODIFICARE)
test2/clientpluto.test	: client di prova pluto(NON MODIFICARE)
test2/clientpluto.check: output atteso pluto(NON MODIFICARE)
test2/outtest.check	: file di output atteso  (NON MODIFICARE)

lcschat/test-frag2	  : script di test
lcschat/checktestfrag2out : script di controllo dell'output del test
			  test-frag2

------------------------------------------------
Cosa deve essere realizzato per il frammento2 :
------------------------------------------------
** NB: leggere accuratamente la specifica complessiva del progetto disponibile 
sul sito prima di procedere alla lettura della descrizione delle parti da 
realizzare ****************************************************************8

Il secondo frammento prevede la realizzazione di 

1) uno script bash "checkAll":

Lo script  effettua il test automatico di tutti gli
eseguibili presenti in una directory passata come parametro. La specifica di
questo script coincide con l'esercizio numero 6 dell'esercitazione 6
(01/03/06 (B) e ven 03/03/06 (A))
Questo script ***non deve essere*** sviluppato da 
chi sta svolgendo il progetto come
progetto di recupero di LPS o LPC. Questi studenti devono usare il Makefile2
per il testing e la consegna. 

2) il server della chat (file server.c)

Il server e' multithreaded. All'avvio il thread principale effettua i vari
controlli sui parametri passati e poi prosegue le operazioni in backgroud
(usando la SC fork(), vedi esercizio 4 del gruppo processi 
nell'esercitazione 12).

Successivamente si mette in attesa su un socket su cui i
client inviano le richieste di comnnessione. Appena un client si connette,
viene creato un socket privato ed attivato un thread dedicato che serve tutte
le richieste successive da quel client (fino alla exit).

Tutti i thread attivi ad un determinato istante condividono la tabella hash in
cui sono registrati i nomi degli utenti attualmente connessi (campo key) ed il
file descriptor del socket corrispondente (per eventuali scritture di
messaggi). 

-----------------------------
 Come sviluppare il server
-----------------------------
1) STUDIO COMPORTAMENTO SERVER e CLIENT
  
  Nella cartella ./bin, si trovano tre eseguibili: 

  * server, un eseguibile di prova che implementa il server
  
  * client, un client realizzato con le librerie libMainWindow.a, che
  realizza l'interfaccia utente richiesta dal progetto da usare per 
  il testing manuale dell'applicazione
  
 * testclient, un client realizzato con le librerie libtestMainWindow.a che ha
 lo stesso funzionamento di "client", eccetto che la lettura dei comendi
 avviene da stdin, e la scrittura dei messaggi avviene su stdout (questo
 permette di automatizzare piu' agevolmente i test)

==> utilizzateli per sperimentare il funzionamento del server e del client, sia
nella configurazione finale che in quella di test.

2) STUDIO LIBRERIA DI COMUNICAZIONE

  La libreria di comunicazione viene fornita agli studenti gia' pronta in
   ./lib/libcom.a, il suo header e' "lcscom.h":

==> leggete attentamente le specifiche nel testo del progetto ed i commenti
relativi alle varie funzioni nel lcscom.h.

3) MODIFICA DELLA TABELLA HASH (realizzata nel primo frammento) PER RENDERE
   POSSIBILE LA CONDIVISIONE FRA PIU' THREAD SENZA SIDE EFFECT.

   A questo scopo, le specifiche dell funzioni putHash() e getHash() 
   sono state modificate rispetti al primo frammento. Infatti,
   non restutuiscono piu' il puntatore all'elemento, che creerebbe una
   condivisione fra thread di difficile gestione. In particolare, la
   putHash(), ritorna semplicemente NULL se si e' verificato un errore e un
   valore !=NULL altrimenti. Invece la getHash(), ritorna una copia esplicita
   dell'elemento trovato (se presente). La copia deve essere poi
   deallocata da chi ha chiamato la getHash(). 
   test-frag1.c e' stato opportunamente adattato per tener conto di queste
   modifiche. In particolare, il vostro codice non passa piu' il test
   in quanto vengono effettuate due deallocazioni in piu'.

4) PROGETTAZIONE ed IMPLEMENTAZIONE del codice del SERVER
   
   Il server deve essere realizzato utilizzando i pthread(), ed
   l'implementazione complessiva deve trovarsi nel file "server.c". Chi
   volesse suddividere il server su piu' file puo' farlo, modificando il
   makefile limitatamente alla sezione (**1**), non e' ammesso aggiungere o
   modificare i target della sezione (**2**).

------------------
Come procedere :
-----------------

0) leggere attentamente il README e capire il funzionamento il codice fornito
dai docenti (codice C, script, Makefile)

1) analizzare accuratamente i file test2/*.check (che forniscono l'output
atteso dai test) per capire come deve essere formattato ogni messaggio

2) implementare le funzioni richieste ed effettuare testing
   preliminare utilizzando ove necessario, gli eseguibili in bin/

3) testare il software complessivo con makefile fornito dai
  docenti. E' necessario prima settare la variabile di
  ambiente MALLOC_TRACE in modo che contenga la stringa "./mtrace.log" e poi
  procedere al test invocando i target "test1" e "test2", cioe'
  eseguire quanto segue 
        
       bash:~$ export MALLOC_TRACE="./.mtrace.log"
       bash:~$ make test1
       bash:~$ make test2

( oppure 

       bash:~$ make -f Makefile2 test1
       bash:~$ make -f Makefile2 test2

per chi deve recuperare LPS o LCS)

  NOTA: (1) non deve essere modificata la struttura delle directory
  interne a lcschat/
  (2) E' importante che il test1/test2 vengano effettuati solo su
  un programma gia' funzionante altrimenti i risultati possono essere di
  difficile interpretazione, fuorvianti o inutili.

4) preparare la documentazione: ovvero commentare adeguatamente i file
   *.c e *.h ed inserire una intestazione contenente il nome dei
   componenti del gruppo e una dichiarazione di originalita' ad esempio:

   /* File : lcshash.c
     Autori: Nino Bixio, Giuseppe Garibaldi
     Si dichiara che il contenuto di questo file e' in ogni sua parte opera
     originale degli autori sopracitati.  */

5) controllare il file "gruppo.txt" con i nomi ed i dati dei componenti del
   gruppo e 

6) consegnare il file ESCLUSIVAMENTE eseguendo

      bash:~$ make consegna2

( oppure 

       bash:~$ make -f Makefile2 consegna2

per chi deve recuperare LPS o LCS)

   e seguendo le istruzioni. Anche in questo caso occorre  che la variabile
   MALLOC_TRACE sia settata a "./mtrace.log".
   Per la consegna e' necessaria l'utility "mpack" installata solo nelle
   macchine dei laboratori H, M ed I e su trudy. 
   Per consegne da altre macchine e'
   possibile scaricare il binario di 'mpack' dal sito del corso. 


---------------------------------------
 NOTE IMPORTANTI: LEGGERE ATTENTAMENTE
---------------------------------------

1) gli eleborati non consegnati con "make consegna2" non verranno accettati

2) tutti gli elaborati verranno confrontati fra di loro con tool automatici
   per stabilire eventali situazioni di PLAGIO. Se tali situazioni si
   verificheranno *tutti* gli elaborato coinvolti verranno annullati con
   conseguente perdita del bonus. 

3) Tutti gli studenti coinvolti in un episodio di PLAGIO comprovato dovranno
   re-implementare il frammento incriminato e saranno sottoposti ad una prova
   orale supplementare. In caso di recidive verranno esclusi dalla
   possibilita' di sostenere l'esame per TUTTO IL RESTO DELL'ANNO ACCADEMICO
   in CORSO.

4) Chi in sede di orale risulta palesemente non essere l'autore del software
   consegnato in uno dei frammenti verra' escluso dalla possibilita' di
   sostenere l'esame per TUTTO IL RESTO DELL'ANNO ACCADEMICO in CORSO.

5) Tutti i comportamenti scorretti ai punti 3 e 4 verranno segnalati
   ufficialmente al presidente del corso di laurea, che si riserva di
   decidere azioni disciplinari supplementari a quelle sopra descritte.
